/********************************************************************************
 * Project Name		[JavaEE_Web]
 * File Name     	[Servlet02.java]
 * Creation Date 	[2015-01-01]
 * 
 * Copyright© ge.y.yang@gmail.com All Rights Reserved
 * 
 * Work hard, play harder, think big and keep fit
 ********************************************************************************/
package _notes.servlet;

/**
 * Servlet API
 * 
 * @author 不落的太阳(Sean Yang aka ShortPeace)
 * @version 1.0
 * @since jdk 1.8
 * 
 */
public final class Servlet02 {

	public void servletConfig() {
		/**
		 * ServletConfig<br/>
		 * 
		 * 封装了Servlet的配置信息[配置在<servlet>标签中的<init-param>]<br/>
		 * 可以获得ServletContext对象<br/>
		 * 
		 * 主要方法<br/>
		 * getInitParameter(String paramName);<br/>
		 * getInitParameterNames();<br/>
		 * getServletName();<br/>
		 */
	}

	public void servletContext() {
		/**
		 * ServletConetext<br/>
		 * 
		 * 该对象代表当前应用, 可以从当前Web应用中获取各种信息[配置在web.xml中的<context-param>标签中]<br/>
		 * 
		 * 主要方法<br/>
		 * getInitParameter(String paramName);<br/>
		 * getInitParameterNames();<br/>
		 * getRealPath(String path); 获取当前Web应用的某个文件在服务器上的绝对路径<br/>
		 * getContextPath();获取当前Web应用的名称<br/>
		 * getResourceAsStream(String path);获取当前Web应用的某个文件对应的输入流<br/>
		 * forward(ServletRequest request, ServletResponse response); 请求转发<br/>
		 */
	}

	public void genericServlet() {
		/**
		 * GenericServlet<br/>
		 * 
		 * 1. GenericServlet是一个Servlet, 是Servlet接口和ServletConfig接口的实现类, 为抽象类,
		 * service()方法为其抽象方法 <br/>
		 * 2. 其中声明了一个ServletConfig类型的成员变量, 在init(ServletConfig config)方法中初始化,
		 * 利用servletConfig成员变量实现了ServletConfig接口的方法<br/>
		 * 3. 其还定义了一个init()方法, 被init(ServletConfig config)方法调用<br/>
		 * 4. 建议子类覆盖init()方法, 不建议覆盖init(ServletConfig config)方法<br/>
		 * 5. 如果覆盖init(ServletConfig config)方法, 则必须显式调用super.init(config)方法,
		 * 否则调用this.getServletConfig()方法将会抛出NullPointerException<br/>
		 * 6. init()方法并不是Servlet生命周期方法, init(ServletConfig config)方法是生命周期方法<br/>
		 */
	}

	public void servletRequest() {
		/**
		 * ServletRequest<br/>
		 * 
		 * 该对象封装了请求信息<br/>
		 * 
		 * 主要方法<br/>
		 * getParameter(String name); 获得指定请求参数名称的参数值;<br/>
		 * getParameterValues(String name); 获得指定请求参数名称的参数值, 适用于checkbox等有多个值的组件
		 * <br/>
		 * getParameterNames(); 获得所有请求参数的名称<br/>
		 * getParameterMap(); 获得一个Map, key是请求参数名, value是请求参数值组成的数组<br/>
		 * 
		 * HttpServletRequest是SerlvetRequest的子接口, 针对于Http请求定义, 包含了获取Http请求相关的方法
		 * <br/>
		 * HttpServletRequest的方法<br/>
		 * getRequestURI(); 返回请求的地址[/MyWebApp/servletRequest]<br/>
		 * getRequestURL();
		 * 返回请求的地址[http://localhost:8080/MyWebApp/servletRequest]<br/>
		 * getMethod(); 返回请求的方式GET/POST<br/>
		 * getQueryString(); 如果是GET请求, 获取请求参数对应的字符串[?后的字符串]<br/>
		 * getServletPath(); 获取请求的Servlet的映射路径<br/>
		 */
	}

	public void servletResponse() {
		/**
		 * ServletResponse<br/>
		 * 
		 * 该对象封装了响应信息<br/>
		 * 
		 * 主要方法<br/>
		 * setHeader(); 设置响应头<br/>
		 * setContentType(); 设置响应的内容类型[相关类型参照TomcatHome/conf/web.xml]<br/>
		 * getWriter(); 返回PrintWriter对象, 调用该对象的print()方法, 输出文本数据<br/>
		 * getOutputStream(); 返回ServletOuputStream对象, 调用该对象的write()方法, 输出二进制数据
		 * <br/>
		 * 
		 * 注意:<br/>
		 * 1. getOutputStream()和getWriter()这两个方法互相排斥, 只能调用其一<br/>
		 * 2.
		 * Servlet程序向ServletOutputStream或PrintWriter对象中写入的数据将被Servlet引擎从response里面获取,
		 * Servlet引擎将这些数据当作响应消息的正文, 然后再与响应状态行和各响应头组合后输出到客户端<br/>
		 * 3. Servlet的service方法结束后,
		 * Servlet引擎将检查getWriter或getOutputStream方法返回的输出流对象是否已经调用过close方法, 如果没有,
		 * Servlet引擎将调用close方法关闭该输出流对象<br/>
		 * 
		 * HttpServletResponse是ServletResponse的子接口, 针对于Http响应定义,
		 * 包含了针对Http响应相关的方法 <br/>
		 * 
		 * HttpServletResponse的具体应用场景示例<br/>
		 * 
		 * 1. 设置Http响应头控制浏览器禁止缓存当前文档内容<br/>
		 * <code>
		 * response.setDateHeader("expries", -1);
		 * response.setHeader("Cache-Control", "no-cache");
		 * response.setHeader("Pragma", "no-cache");
		 * </code><br/>
		 * 2.设置Http响应头控制浏览器定时刷新网页<br>
		 * <code>
		 * response.setHeader("refresh", "5");
		 * </code><br/>
		 * 3. 请求重定向 response.sendRedirect(String location);<br/>
		 * 4. 其他, 参见servlet.api.TestServletResponse<br/>
		 */
	}

	public void httpServlet() {
		/**
		 * HttpServlet<br/>
		 * 
		 * 1. HttpServlet是一个Servlet, 继承自GenericServlet, 针对Http协议定制<br/>
		 * 
		 * 2. 在service()方法中<br/>
		 * 将ServletRequest转换为了HttpServletRequest<br/>
		 * 将ServletResponse转换为了HttpServletResponse<br/>
		 * 并调用了重载的service(HttpServletRequest request, HttpServletResponse
		 * response)方法, 在service()方法中获取了请求方式[request.getMethod()],
		 * 根据请求方式有创建了doXXX()方法[XXX为具体的请求方式, 比如Get, Post]<br/>
		 * 
		 * 3. 实际开发中, 直接继承HttpServlet, 重写doXXX()方法,
		 * 该方法直接使用HttpServletRequest和HttpServletResponse作为参数<br/>
		 */
	}

	public void requestDispatcher() {
		/**
		 * RequestDispatcher<br/>
		 * 
		 * 1. RequestDispatcher实例对象是由Servlet引擎创建的<br/>
		 * 
		 * 2. RequestDispatcher用于包装一个要被其他资源调用的资源[Servlet, HTML文件, JSP文件等],
		 * 并可以通过其中的方法将客户端的请求转发给所包装的资源<br/>
		 * 
		 * 3. RequestDispatcher接口中定义了两个方法: forward方法和include方法<br/>
		 * 
		 * 4. forward()方法和include()方法
		 * 方法接收的两个参数必须是传递给当前Servlet的service方法的那两个ServletRequest和ServletResponse对象
		 * 或者是对它们进行了包装的ServletRequestWrapper或ServletResponseWrapper对象<br/>
		 * 
		 * 5.获取RequestDispatcher对象的方法:<br/>
		 * ServletContext.getRequestDispatcher[参数只能是以"/"开头的路径]<br/>
		 * ServletContext.getNamedDispatcher<br/>
		 * ServletRequest.getRequestDispatcher[参数可以是不以"/"开头的路径]<br/>
		 */
	}

	public void httpServletRequestWrapper() {
		/**
		 * HttpServletRequestWrapper<br/>
		 * HttpServletResponseWrapper<br/>
		 * 
		 * HttpServletResponseWrapper类包装了原始的HttpServletRequest对象,
		 * 它实现了HttpServletRequest接口中的所有方法, 这些方法的内部实现都是仅仅调用了一下所包装的的Request对象的对应方法
		 * <br/>
		 *
		 * HttpServletResponseWrapper类来包装原始的response对象<br/>
		 * 
		 * HttpServletResponseWrapper和HttpServletResponseWrapper用于对HttpServletRequest或HttpServletResponse的某一个方法进行修改或增强
		 * <br/>
		 * 示例: 过滤dirty words, 详见filter.cases.DirtyWordsFilter<br/>
		 */
	}
}
